home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc™ Source Code / Storage / Bento / CM / FreeSpce.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-08-28  |  10.4 KB  |  234 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        FreeSpce.h 
  3.  
  4.     Contains:    Container Manager Free Space Value Management Interfaces
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1992-1994 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <3>     12/9/94    EL        #1182275 Add cmRemoveSmallFreeSpace.
  15.          <2>     8/26/94    EL        #1182275 Add routines for handling the
  16.                                     temporary free list.
  17.          <2>      5/9/94    MB        #1162181: Changes necessary to install MMM.
  18.          <1>      2/3/94    EL        first checked in
  19.          <3>     1/19/94    EL        Add cmCopyTmpFreeToTOC to add temp free
  20.                                                     space to the permanent free space.
  21.          <2>      1/6/94    EL        Add cmTakeOverFreeList call to transfer the
  22.                                                     free list.
  23.  
  24.     To Do:
  25. */
  26.  
  27. /*---------------------------------------------------------------------------*
  28.  |                                                                           |
  29.  |                            <<< FreeSpce.h  >>>                            |
  30.  |                                                                           |
  31.  |         Container Manager Free Space Value Management Interfaces          |
  32.  |                                                                           |
  33.  |                               Ira L. Ruben                                |
  34.  |                                 4/23/92                                   |
  35.  |                                                                           |
  36.  |                    Copyright Apple Computer, Inc. 1992-1994               |
  37.  |                           All rights reserved.                            |
  38.  |                                                                           |
  39.  *---------------------------------------------------------------------------*
  40.  
  41.  This file contains interfaces for reusing deleted data space.  The routines record the
  42.  deleted space and reuse it for value data writes.
  43.  
  44.  The free space is maintained as a list of value segment entries for a "free space"
  45.  property belonging to the TOC ID 1 entry.  It is written to the container like other ID 1
  46.  properties to keep track of all the deleted space.
  47.  
  48.  If a container is opened for reusing free space, we use the free list to reuse the space.
  49. */
  50.  
  51.  
  52. #ifndef __FREESPACE__
  53. #define __FREESPACE__
  54.  
  55.  
  56. #ifndef __CMTYPES__
  57. #include "CMTypes.h"
  58. #endif
  59. #ifndef __CM_API_TYPES__
  60. #include "CMAPITyp.h"
  61. #endif
  62. #ifndef __TOCENTRIES__
  63. #include "TOCEnts.h"   
  64. #endif
  65. #ifndef __CONTAINEROPS__
  66. #include "Containr.h"  
  67. #endif
  68.  
  69.                                                                     CM_CFUNCTIONS
  70.  
  71. struct FreeSpaceItem {        /* this is used to store an item in the temporary free space */
  72.     ListLinks        theList;    /* Must be first entry. */
  73.     CM_ULONG        offset;        /* Offset into file. */
  74.     CM_ULONG        size;        /* Size of block to free. */
  75. };
  76. typedef struct FreeSpaceItem FreeSpaceItem;
  77.  
  78. void cmCopyTmpFreeToTOC(ContainerPtr container);
  79.     /*
  80.     This routine takes the temporary free space and merge it into the permanent free space.
  81.     */
  82.  
  83. void cmAddToFreeList(ContainerPtr container, TOCValuePtr theValueToFree,
  84.                                          CM_ULONG offset, CM_ULONG size);
  85.     /*
  86.     This routine is called whenever space for value data is to be freed.  The space is
  87.     recorded in a free list. The free list entries are maintained as value segments belonging
  88.     to the "free space" property of TOC object ID 1.
  89.     
  90.     The amount of space to be freed is specified in one of two possible ways:
  91.     
  92.          1. By passing a pointer to a value segment in theValueToFree.  The offset and size
  93.                 are extracted from the segment info.  If theValueToFree is for an immediate value,
  94.                 we simply exit since there is no container space to actually free.  Global names,
  95.                 as usual, are handled specially.  In particular, for no global names that have not
  96.                 yet been written to the container yet (we keep 'em in memory unto we write the TOC
  97.                 at container close time), then we ingore them just like immediates.  For "old"
  98.                 global names we do account for the space.
  99.                 
  100.          2. If theValueToFree is passed as NULL, then an explicit size and offset may be
  101.                 passed.  Note that a non-null theValueToFree has precedence over explicit offset
  102.                 and size.
  103.                 
  104.      As part of the freeing process, we scan the free list to see if the new space can be 
  105.      combined with an already existing entry.  It's a sort of on-the-fly garbage collector.
  106.      
  107.      For new containers, there is no "free space" property initially for ID 1.  It is created
  108.      here the first time we need to free space.  We remember the value header for the "free
  109.      space" property so that we may efficiently get at the list on all future calls.
  110.     */
  111.  
  112. void cmAddValueToTmpFreeList(TOCValueHdrPtr theValueHdr);
  113.     /*
  114.         This routine put all the free space used by a value into the temporary free list
  115.     */
  116.  
  117. void cmAddToTmpFreeList(ContainerPtr container, CM_ULONG offset, CM_ULONG size);
  118.     /*
  119.         This routine takes some free space and put it into the temporary free space property
  120.         for use in future.
  121.         
  122.         We want to put thing in the temporary free list for two reasons.
  123.         
  124.         For container opened for writing, we don't want to write into the old container
  125.         before we close it in case it crashes before it is closed, so we put it into
  126.         the temporary free list.
  127.         
  128.         For container opened for updating, we have free space that can be reused if
  129.         it is merged. Since we do not know whether we will just close the container
  130.         or merge it, we put it in the temporary free list and put it on the real
  131.         free list only if we do a merge at close time.
  132.     */
  133.  
  134.  
  135. void cmRemoveSmallFreeSpace(ContainerPtr container);
  136.  
  137.     /* 
  138.      There is certain overhead of storing a value segment. If a free space segment is so small
  139.      that the overhead of storing it is greater than the free space itself, then it is not
  140.      worth to keep the free space. So we go through the free space list and remove the small
  141.      segments.
  142.      
  143.      On the other hand, later we may free space that are are around these small segments.
  144.      So if we ignore these small segments, we may cause fragmentation of the free space
  145.      later. So we should revisit this issue to see if it is worthwhile to keep them anyway.
  146.     */
  147.  
  148. CM_ULONG cmGetFreeListEntry(ContainerPtr container, 
  149.                                                         CM_ULONG desiredSize, Boolean mustAllFit,
  150.                                                         CM_ULONG *actualSize);
  151.     /*
  152.     This routine returns one free list entry (if one exists).  The offset from that entry is
  153.     returned as the function result.  The size is returned in actualSize.  If there is no 
  154.     free space, or we can't find one big enough (see mustAllFit below), 0 is returned as the
  155.     function result and for the actualSize.  0's are also returned if the container was not
  156.     opened to reuse free space.
  157.     
  158.     The desiredSize is passed as what the caller would like as the single free list entry
  159.     amount, i.e., a "best fit".  It is also used when we find a bigger free list entry and
  160.     only have to reduce part of it.
  161.     
  162.     If mustAllFit is true, then we MUST find a single free list segment big enough or 0 will
  163.     be returned.  This is used for data that is not allowed to be continued with multiple
  164.     value segments (e.g., global names).
  165.     
  166.     The free list is built by cmAddToFreeList() as value segments belonging to a value header
  167.     of the "free space" property for TOC object ID 1.   If all the free list entries are
  168.     exhausted, the value header is freed along with the property.  If space is ever given up
  169.     after this through cmAddToFreeList(), it will recreate the "free space" property, its
  170.     value header, and the free list value entry segments.
  171.     */
  172.     
  173. void cmTakeOverFreeList(ContainerPtr toContainer, ContainerPtr container);    
  174.     /*--------------------------------------------------------------------------*
  175.      | cmTakeOverFreeList - have one container take the free space from another |
  176.      *--------------------------------------------------------------------------*
  177.      
  178.      When a target container is open by a container, we want to take over the
  179.      free space in the target container so that we can reuse the free space
  180.      in the target container. Since the target container is open read only, we
  181.      cannot update the free space list there. So the update container move the list
  182.      over so that it becomes the free list of the update container.
  183.      
  184.      This should only be done for one level, so the update container takes the
  185.      free list of the target container. Any free list that is in container that
  186.      is further down may be used already and should not be used.
  187.     */
  188.     
  189. CM_ULONG cmWriteData(TOCValueHdrPtr theValueHdr, CM_UCHAR *buffer, CM_ULONG size);
  190.     /*
  191.     This routine is the Container Manager's low-level value data writer.  It takes a value
  192.     header, and size bytes in the buffer and writes it to the container via the output
  193.     handler.  The amount written is returned.  If it is not equal to the passed size, the
  194.     caller should report an error.
  195.     
  196.     The reason this routine is used rather than using the CMfwrite() handler call directly is
  197.     that this routine checks to see if the container has been opened to reuse free space.  If
  198.     it hasn't, we degenerate into a simple CMfwrite() call.  If it has, then we use the free
  199.     list, built by cmAddToFreeList(), to write out the data segments to reuse the free space.
  200.     
  201.   In all cases the data written is recorded as value segments in the value list belonging
  202.   to the specified value header. The new segments are appended on to the END of the segment
  203.     list.  It is up to the caller to guarantee this is where the segments are to go.  The
  204.     continued flags are appropriately set.
  205.     
  206.     Note, as just mentioned, use this routine ONLY for appending data segments to a value.
  207.     Also, use this routine ONLY if continued segments are permitted for the data.  This means
  208.     you cannot call this routine to write global names.  They are always written as single
  209.     segments.
  210.     
  211.     Even with these restrictions, for the main case, i.e., CMWriteValueData(), this is not a
  212.     problem.  CMWriteValueData() is the primary caller.  It knows what it's doing with the
  213.     data (lets hope so).  So it knows when to call us here.
  214.     
  215.     The net effect is to reuse free space whenever we can if the container was opened for
  216.     updating, and to do straight CMfwrite() otherwise.
  217.     */
  218.  
  219.  
  220. void cmDeleteFreeSpace(ContainerPtr container, CM_ULONG beyondHere);
  221.     /*
  222.     This routine is called to remove all free list entries that have their space beyond the
  223.     specified offset, beyondHere.  All entries with starting offsets greater than or equal
  224.     to beyondHere are removed.  If one spans beyondHere it will be reduced appropriately.
  225.     
  226.     These entries are removed so so that we may overwrite from beyondHere with a new TOC.
  227.     Since we are reusing that space for the TOC we obviously can't keep free list entries for
  228.     it.
  229.     */
  230.     
  231.  
  232.                                                           CM_END_CFUNCTIONS
  233. #endif
  234.